The Session Object

Purpose: The Session object ⎕SE is a special system object that represents the session window and acts as a parent for the session menus, tool bar(s) and status bar.
Children Form, MenuBar, Menu, MsgBox, Font, FileBox, Printer, Bitmap, Icon, Cursor, Clipboard, Locator, Timer, Metafile, ToolBar, StatusBar, TipField, TabBar, ImageList, PropertySheet, OLEClient, TCPSocket, CoolBar, ToolControl, BrowseBox
Properties Type, Caption, Posn, Size, File, Coord, State, Event, FontObj, YRange, XRange, Data, TextSize, Handle, HintObj, TipObj, CurObj, CurPos, CurSpace, Log, Input, Popup, RadiusMode, LogFile, MethodList, ChildList, EventList, PropList
Methods ChooseFont, FileRead, FileWrite
Events Close, Create, FontOK, FontCancel, WorkspaceLoaded, SessionPrint, SessionTrace

Description

There is one (and only one) object of type Session and it is called ⎕SE. You may use ⎕WG, ⎕WS and ⎕WN to perform operations on ⎕SE, but you cannot expunge it with ⎕EX nor can you recreate it using ⎕WC. You may however expunge all its children. This will result in a bare session with no menu bar, tool bar or status bar.

⎕SE is loaded from a session file when APL starts. The name of the session file is specified by the session_file parameter. If no session file is defined, ⎕SE will have no children and the session will be devoid of menu bar, tool bar and status bar components.

An additional feature is provided to establish code in the Session. See .

You may use all of the standard GUI system functions to build or configure the components of the Session to your own requirements. You may also control the Session by changing certain of its properties.

Note that the Session reports a Create event when APL is first started, and a WorkspaceLoaded event when a workspace is loaded or on a clear ws.

The Session reports a SessionPrint event when certain types of output are about to be displayed. This may be used to alter the normal default display. The Session also reports a SessionTrace event when executing when an expression is execute with trace control. This may be used to alter the normal default trace.

Read-Only Properties

The following properties of ⎕SE are read-only and may not be set using ⎕WS:

Property Description
Type A character vector containing 'Session'
Caption A character vector containing the current caption in the title bar of the Session window.
TextSize Reports the bounding rectangle for a text string. For a full description, see TextSize in Object Reference.
CurObj A character vector containing the name of the current object. This is the name under or immediately to the left of the input cursor.
CurPos A 2-element integer vector containing the position of the input cursor (row and column number) in the session log. This is ⎕IO dependent. If ⎕IO is 1, and the cursor is positioned on the character at the beginning of the first (top) line in the log, CurPos is (1 1). If ⎕IO is 0, its value would be (0 0).
CurSpace A character vector which identifies the namespace from which the current expression was executed. If the system is not executing code, CurSpace is the current space and is equivalent to the result of ⊃''⎕NS''.
Handle The window handle of the Session window.
Log A vector of character vectors containing the most recent set of lines (input statements and results) that are recorded in the session log. The first element contains the top line in the log.
Input A vector of character vectors containing the most recent set of input statements (lines that you have executed) contained in the input history buffer.
LogFile The name of the session log file in use.
ChildList A vector of character vectors containing the types of object that can be created as a child of ⎕SE.
MethodList A vector of character vectors containing the names of the methods associated with ⎕SE.
EventList A vector of character vectors containing the names of the events generated by ⎕SE
PropList A vector of character vectors containing the names of the properties associated with ⎕SE.

Read/Write Properties

The following properties of ⎕SE may be changed using ⎕WS:

Property Description
Caption A character vector containing the current caption in the title bar of the Session window. See Session Caption.
Coord Specifies the co-ordinate system for the session window.
Data May be used to associate arbitrary data with the session object ⎕SE.
Event You may use this property to attach an expression or callback function to the Create event or to user-defined events. A callback attached to the Create event can be used to initialise the Session when APL starts.
File The full pathname of the session file that is associated with the current session. This is the file name used when you save or load the session by invoking the FileRead or FileWrite method.
FontObj Specifies the APL font. In general, the FontObj property may specify a font in terms of its face name, size, and so forth or it may specify the name of a Font object. For applications, the latter method is recommended as it will result in better management of font resources. However, in the case of the Session object, it is recommended that the former method be used.
HintObj Specifies the name of the object in which hints are displayed. Unless you specify HintObj individually for session components, this object will be used to display the hints associated with all of the menu items, buttons, and so forth in the session. The object named by this property is also used to display the message "Ready..." when APL is waiting for input.
Popup A character vector that specifies the name of a popup menu to be displayed when you click the right mouse button in a Session window.
Posn A 2-element numeric vector containing the position of the top-left corner of the session window relative to the top-left corner of the screen. This is reported and set in units specified by the Coord property.
Size A 2-element numeric vector containing the height and width of the session window expressed in units specified by the Coord property.
State An integer that specifies the window state (0=normal, 1=minimised, 2=maximised). You may wish to use this property to minimise and later restore the session under program control. If you save your session with State set to 2, your APL session will start off maximised.
TipObj Specifies the name of the object in which tips are displayed. Unless you specify TipObj individually for session components, this object will be used to display the tips associated with all of the menu items, buttons, and so forth in the session.
XRange See Object Reference
YRange See Object Reference

Special Properties

The following properties of ⎕SE are used internally by Dyalog tools such as SALT. They are not intended nor supported for general use and are not reported by PropList.

StatusWindow This read-only property returns a reference to the Status Window. The expression: (⎕SE.⎕WG'StatusWindow')⎕WG'Text' returns the (read-only) contents of the status window.
Editor This read-only property returns a reference to the Editor Window. The Editor generates the special events Fix, AfterFix and Format.

Special Events

The following special events are generated by ⎕SE or its child objects. They are used internally by Dyalog tools such as SALT. They are not intended nor supported for general use.

AfterFix This event is reported by the Editor after it has successfully fixed a new object, or a new version of an object, in the workspace.
Fix This event is reported by the Editor when the user attempts to fix an object.
Format This event is reported by the Editor when the user attempts to format an object.
SessionPrint This event is reported when a value is about to be displayed in the Session window. The default display of the value may be intercepted by a callback function and displayed differently. This event is used by the ]box and ]rows user commands.
SessionTrace This event is reported when an expression is executed with trace control. The trace behaviour may be intercepted by a callback function and altered. This event is used by the ]box and ]rows user commands.
WorkspaceLoaded This event is generated when a workspace is loaded or upon )CLEAR.

Session Caption

The Caption property of the Session may be set dynamically to a character vector comprising free text and field names. Field names must be enclosed in braces and are replaced in-situ by corresponding values.

Field Name Description
{TITLE} the window specific text
{WSID} ⎕WSID
{NSID} current namespace
{SNSID} short version of namespace (no #.)
{PRODUCT} for example, Dyalog APL/W
{VER_A} for example, 19
{VER_B} for example, 0
{VER_C} for example, 47586 (SVN revision)
{PID} process ID (decimal)
{CHARS} "Classic" or "Unicode"
{BITS} "32" or "64"

Table 73: Session Caption Fields

Example:

     ⎕SE.Caption←'Pete: {WSID} {Product} {VER_A}.{VER_B}'

The Session caption in a CLEAR WS will change to:

     Pete: CLEAR WS Dyalog APL/W-64 19.0

Note that Caption returns the codified string used to set it.

     ⎕SE.Caption
Pete: {WSID} {Product} {VER_A}.{VER_B}